<?php
/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
namespace protocol\translation\framework\services\base;

/**
 * <p>
 * The converter interface is implemented for different protocol implementations in order to adapt
 * a RESTful One API service to the delegation protocols like SMPP, MMS or Diameter.
 * </p>
 *
 * <p>
 * Implementations should extract the request arguments which will be forwarded to the protocol
 * client implementation.
 * </p>
 *
 * <p>
 * Implementations will also convert a protocol message response into a format that can be returned
 * to the caller like json or xml depending on implementation.
 * </p>
 *
 * <p>
 * Thread Safety: Implementations of this interface should be thread safe.
 * </p>
 *
 * <p>
 * <strong>Sample Code Usage</strong>
 * <code>
 * // Create a new instance
 * $converter = new SMPP_JSON_Converter();
 *
 * // Convert to JSON
 * $json = $converter->convertTo(array("senderAddress" => "Some Addr"), "query delivery status");
 *
 * // Convert from name/value parameter pairs
 * $data = $converter->convertFrom(
 *     "notifyURL=http%3A%2F%2Fnotify&callbackData=CallbackData", "subscribeToSMSDeliveryNotifications"
 * );
 * // Get the notify URL
 * $notifyUrl = $data["notifyURL"]; // http://notify
 *
 * // Get the callback data
 * $callbackData = $data["callbackData"]; // CallbackData
 * </code>
 * </p>
 *
 * @author hpana, akinwale
 * @version 1.0
 */
interface Converter {
    /**
     * <p>
     * This method is used to convert the protocol response to a format that can be used by the frontend.
     * </p>
     *
     * @param array $protocolMessage the response from the protocol message
     * @param string $operation this represents the OneAPI operation type also refered to as method
     *                   name because each service method implements one OneAPI protocol operation
     *
     * @return string the converted response
     *
     * @throws IllegalArgumentException if any argument is unset, protocolMessage is not of array type or
     *             if any array element is unset or if operation is an empty string or not of string type
     *             or not supported
     * @throws ConversionException if any other error occurs
     */
    public function convertTo($protocolMessage, $operation);

    /**
     * <p>
     * This method is used to convert from the requeset message body to an array of values to
     * be used for calling the dependent protocol.
     * </p>
     *
     * @param string $messageBody the request message body from which to extract the array of
     *                   parameters for calling the protocol
     * @param string $operation this represents the OneAPI operation type also refered to as method
     *                   name because each service method implements one OneAPI protocol operation
     *
     * @return array the array of parameters for calling the protocol
     *
     * @throws IllegalArgumentException if any argument is unset, empty string or not of string type
     *             of if operation is not supported
     * @throws MissingMandatoryParametersException if required parameters are missing
     * @throws ConversionException if any other error occurs
     */
    public function convertFrom($messageBody, $operation);
}

?>